home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 52 / Amiga Format AFCD52 (Issue 136, May 2000).iso / -serious- / programming / c / icu-1.3.1 / icu-bin / include / ures.h < prev    next >
C/C++ Source or Header  |  2000-02-23  |  14KB  |  322 lines
  1. /*
  2. *******************************************************************************
  3. *                                                                             *
  4. * COPYRIGHT:                                                                  *
  5. *   (C) Copyright Taligent, Inc.,  1997                                       *
  6. *   (C) Copyright International Business Machines Corporation,  1997-1999     *
  7. *   Licensed Material - Program-Property of IBM - All Rights Reserved.        *
  8. *   US Government Users Restricted Rights - Use, duplication, or disclosure   *
  9. *   restricted by GSA ADP Schedule Contract with IBM Corp.                    *
  10. *                                                                             *
  11. *******************************************************************************
  12. *
  13. * File URES.H (formerly CRESBUND.H)
  14. *
  15. * Modification History:
  16. *
  17. *   Date        Name        Description
  18. *   04/01/97    aliu        Creation.
  19. *   02/22/99    damiba      overhaul.
  20. *   04/04/99    helena      Fixed internal header inclusion.
  21. *   04/15/99    Madhu       Updated Javadoc  
  22. *   06/14/99    stephen     Removed functions taking a filename suffix.
  23. *   07/20/99    stephen     Language-independent ypedef to void*
  24. *******************************************************************************
  25. */
  26.  
  27. #ifndef URES_H
  28. #define URES_H
  29.  
  30. #include "utypes.h"
  31.  
  32.  
  33. #include "uloc.h"
  34.  
  35. /**
  36.  * C API representing a collection of resource information pertaining to a given
  37.  * locale. A resource bundle provides a way of accessing locale- specific information in
  38.  * a data file. You create a resource bundle that manages the resources for a given
  39.  * locale and then ask it for individual resources.
  40.  * <P>
  41.  * The resource bundle file is a text (ASCII or Unicode) file with the format:
  42.  * <pre>
  43.  * .   locale {
  44.  * .      tag1 {...}
  45.  * .      tag2 {...}
  46.  * .   }
  47.  * </pre>
  48.  * The tags are used to retrieve the data later. You may not have multiple instances of
  49.  * the same tag.
  50.  * <P>
  51.  * Four data types are supported. These are solitary strings, comma-delimited lists of
  52.  * strings, 2-dimensional arrays of strings, and tagged lists of strings.
  53.  * <P>
  54.  * Note that all data is textual. Adjacent strings are merged by the low-level
  55.  * tokenizer, so that the following effects occur: foo bar, baz // 2 elements, "foo
  56.  * bar", and "baz" "foo" "bar", baz // 2 elements, "foobar", and "baz" Note that a
  57.  * single intervening space is added between merged strings, unless they are both double
  58.  * quoted. This extends to more than two strings in a row.
  59.  * <P>
  60.  * Whitespace is ignored, as in a C source file.
  61.  * <P>
  62.  * Solitary strings have the format:
  63.  * <pre>
  64.  * .   Tag { Data }
  65.  * </pre>
  66.  * This is indistinguishable from a comma-delimited list with only one element, and in
  67.  * fact may be retrieved as such (as an array, or as element 0 or an array).
  68.  * <P>
  69.  * Comma-delimited lists have the format:
  70.  * <pre>
  71.  * .   Tag { Data, Data, Data }
  72.  * </pre>
  73.  * Parsing is lenient; a final string, after the last element, is allowed.
  74.  * <P>
  75.  * Tagged lists have the format:
  76.  * <pre>
  77.  * .   Tag { Subtag { Data } Subtag {Data} }
  78.  * </pre>
  79.  * Data is retrieved by specifying the subtag.
  80.  * <P>
  81.  * Two-dimensional arrays have the format:
  82.  * <pre>
  83.  * .   TwoD {
  84.  * .       { r1c1, r1c2, ..., r1cm },
  85.  * .       { r2c1, r2c2, ..., r2cm },
  86.  * .       ...
  87.  * .       { rnc1, rnc2, ..., rncm }
  88.  * .   }
  89.  * </pre>
  90.  * where n is the number of rows, and m is the number of columns. Parsing is lenient (as
  91.  * in other data types). A final comma is always allowed after the last element; either
  92.  * the last string in a row, or the last row itself. Furthermore, since there is no
  93.  * ambiguity, the commas between the rows are entirely optional. (However, if a comma is
  94.  * present, there can only be one comma, no more.) It is possible to have zero columns,
  95.  * as follows:
  96.  * <pre>
  97.  * .   Odd { {} {} {} } // 3 x 0 array
  98.  * </pre>
  99.  * But it is impossible to have zero rows. The smallest array is thus a 1 x 0 array,
  100.  * which looks like this:
  101.  * <pre>
  102.  * .   Smallest { {} } // 1 x 0 array
  103.  * </pre>
  104.  * The array must be strictly rectangular; that is, each row must have the same number
  105.  * of elements.
  106.  * <P>
  107.  * This is an example for using a possible custom resource:
  108.  * <pre>
  109.  * .    const char *currentLocale;
  110.  * .    UErrorCode success = U_ZERO_ERROR;
  111.  * .    UResourceBundle* myResources=ures_open("MyResources", currentLocale, &success );
  112.  * .
  113.  * .    UChar *button1Title, *button2Title;
  114.  * .    button1Title= ures_get(myResources, "OkKey", &success );
  115.  * .    button2Title= ures_get(myResources, "CancelKey", &success );
  116.  * </pre>
  117.  */
  118.  
  119. /** A UResourceBundle */
  120. typedef void* UResourceBundle;
  121.  
  122.  
  123.  /**
  124.  * Functions to create and destroy resource bundles.
  125.  */
  126.  
  127. /**
  128. *Opens a UResourceBundle, from which users can extract strings by using
  129. *their corresponding keys.
  130. *Note that the caller is responsible of calling <TT>ures_close</TT> on each succesfully
  131. *opened resource bundle.
  132. *@param path  : string containing the full path pointing to the directory
  133. *                where the resources reside (should end with a directory
  134. *                separator.
  135. *                e.g. "/usr/resource/my_app/resources/" on a Unix system
  136. *                if NULL will use the system's current data directory
  137. *@param locale: specifies the locale for which we want to open the resource
  138. *                if NULL will use the default locale
  139. *                
  140. *@param status : fills in the outgoing error code.
  141. * The UErrorCode err parameter is used to return status information to the user. To
  142.      * check whether the construction succeeded or not, you should check the value of
  143.      * U_SUCCESS(err). If you wish more detailed information, you can check for
  144.      * informational error results which still indicate success. U_USING_FALLBACK_ERROR
  145.      * indicates that a fall back locale was used. For example, 'de_CH' was requested,
  146.      * but nothing was found there, so 'de' was used. U_USING_DEFAULT_ERROR indicates that
  147.      * the default locale data was used; neither the requested locale nor any of its
  148.      * fall back locales could be found.
  149. *@return      : a newly allocated resource bundle.
  150. *@see ures_close
  151. */
  152. U_CAPI UResourceBundle*  U_EXPORT2 ures_open(const char*    path,   /* NULL if none */
  153.                        const char*  locale, /* NULL if none */
  154.                        UErrorCode*     status);
  155.  
  156.  
  157. /**
  158. *Opens a UResourceBundle, from which users can extract strings by using
  159. *their corresponding keys. This version of open requires the path 
  160. *string to be of type <TT>const wchar_t*</TT>.
  161. *Note that the caller is responsible of calling <TT>ures_close</TT> on each succesfully
  162. *opened resource bundle.
  163. *@param path: string containing the full path pointing to the directory
  164. *             where the resources reside (should end with a directory
  165. *             separator.
  166. *                e.g. "/usr/resource/my_app/resources/" on a Unix system
  167. *             if NULL will use the system's current data directory
  168. *@param locale: specifies the locale for which we want to open the resource
  169. *                if NULL will use the default locale
  170. *                
  171. *@param status: fills in the outgoing error code.
  172. *@see ures_close
  173. *@return : a newly allocated resource bundle.
  174. */
  175. U_CAPI UResourceBundle* U_EXPORT2 ures_openW(const wchar_t* path, 
  176.                   const char* locale, 
  177.                   UErrorCode* status);
  178.  
  179. /**
  180. *
  181. * returns a resource string, given a resource bundle and a key
  182. *@param resourceBundle: resourceBundle containing the desired string
  183. *@param resourceTag: key tagging the desired string
  184. *@param status: fills in the outgoing error code
  185. *                could be <TT>U_MISSING_RESOURCE_ERROR</T> if the key is not found
  186. *                could be a non-failing error 
  187. *                e.g.: <TT>U_USING_FALLBACK_ERROR</TT>,<TT>U_USING_DEFAULT_ERROR </TT>
  188. *@return: a library-owned zero-terminated unicode string (its lifetime
  189. * is that of the resource bundle.)
  190. *@see ures_getArrayItem
  191. *@see ures_get2dArrayItem
  192. *@see ures_getTaggedItem
  193. */
  194. U_CAPI const UChar* U_EXPORT2 ures_get(const UResourceBundle*    resourceBundle,
  195.                const char*              resourceTag,
  196.                UErrorCode*               status);
  197.  
  198. /**
  199. * returns a resource string which is part of an array, given a resource bundle
  200. * a key to the array and the index of the desired string
  201. *@param resourceBundle: resourceBundle containing the desired string
  202. *@param resourceTag: key tagging the desired array
  203. *@param resourceIndex: index of the desired string
  204. *@param status: fills in the outgoing error code
  205. *                could be <TT>U_MISSING_RESOURCE_ERROR</T> if the key is not found
  206. *                could be a non-failing error 
  207. *                e.g.: <TT>U_USING_FALLBACK_ERROR</TT>,<TT>U_USING_DEFAULT_ERROR </TT>
  208. *@return: a library-owned zero-terminated unicode string (its lifetime
  209. * is that of the resource bundle.)
  210. *@see ures_get
  211. *@see ures_get2dArrayItem
  212. *@see ures_getTaggedItem
  213. */
  214. U_CAPI const UChar* U_EXPORT2 ures_getArrayItem(const UResourceBundle*     resourceBundle,
  215.                     const char*               resourceTag,
  216.                     int32_t                   resourceIndex,
  217.                     UErrorCode*                status);
  218.  
  219. /**
  220. * returns a resource string which is part of a 2D array, given a resource bundle
  221. * a key to the array and the index pair of the desired string
  222. *@param resourceBundle: resourceBundle containing the desired string
  223. *@param resourceTag: key tagging the desired array
  224. *@param resourceIndex: x index of the desired string
  225. *@param resourceIndex: y index of the desired string
  226. *@param status: fills in the outgoing error code
  227. *                could be <TT>U_MISSING_RESOURCE_ERROR</T> if the key is not found
  228. *                could be a non-failing error 
  229. *                e.g.: <TT>U_USING_FALLBACK_ERROR</TT>,<TT>U_USING_DEFAULT_ERROR </TT>
  230. *@return: a library-owned zero-terminated unicode string (its lifetime
  231. * is that of the resource bundle.)
  232. *@see ures_get
  233. *@see ures_getArrayItem
  234. *@see ures_getTaggedItem
  235. */
  236.  
  237. U_CAPI const UChar* U_EXPORT2 ures_get2dArrayItem(const UResourceBundle*   resourceBundle,
  238.                       const char*             resourceTag,
  239.                       int32_t                 rowIndex,
  240.                       int32_t                 columnIndex,
  241.                       UErrorCode*              status);
  242.  
  243. /**
  244. * returns a resource string which is part of a tagged array, given a resource bundle
  245. * a key to the array and the key of the desired string.
  246. *@param resourceBundle: resource bundle containing the desired string
  247. *@param resourceTag: key tagging the desired array
  248. *@param resourceIndex: key tagging the desired string
  249. *@param status: fills in the outgoing error code
  250. *                could be <TT>U_MISSING_RESOURCE_ERROR</T> if the key is not found
  251. *                could be a non-failing error 
  252. *                e.g.: <TT>U_USING_FALLBACK_ERROR</TT>,<TT>U_USING_DEFAULT_ERROR </TT>
  253. *@return: a library-owned zero-terminated unicode string (its lifetime
  254. * is that of the resource bundle.)
  255. *@see ures_get
  256. *@see ures_getArrayItem
  257. *@see ures_get2dItem
  258. */
  259.  
  260. U_CAPI const UChar* U_EXPORT2 ures_getTaggedArrayItem(const UResourceBundle*   resourceBundle,
  261.                       const char*             resourceTag,
  262.                       const char*             itemTag,
  263.                       UErrorCode*              status);
  264.  
  265.  
  266.  
  267. /**
  268. *
  269. *
  270. *@param resourceBundle: resource bundle containing the desired strings
  271. *@param resourceKey: key tagging the resource
  272. *@param err: fills in the outgoing error code
  273. *                could be <TT>U_MISSING_RESOURCE_ERROR</T> if the key is not found
  274. *                could be a non-failing error 
  275. *                e.g.: <TT>U_USING_FALLBACK_ERROR</TT>,<TT>U_USING_DEFAULT_ERROR </TT>
  276. *@return: for    <STRONG>Arrays</STRONG>: returns the number of strings in the array
  277. *                <STRONG>2d Arrays</STRONG>: returns the number of 1d arrays
  278. *                <STRONG>taggedArrays</STRONG>: returns the number of strings in the array
  279. *                <STRONG>single string</STRONG>: returns 1
  280. *@see ures_get
  281. *@see ures_getArrayItem
  282. *@see ures_getTaggedArrayItem
  283. *@see ures_get2dArrayItem
  284. */
  285.  
  286. U_CAPI int32_t U_EXPORT2 ures_countArrayItems(const UResourceBundle* resourceBundle,
  287.                   const char* resourceKey,
  288.                   UErrorCode* err);
  289. /**
  290. * close a resource bundle, all pointers returned from the various ures_getXXX calls
  291. * on this particular bundle are INVALID henceforth.
  292. * @param resourceBundle: a succesfully opened resourceBundle.
  293. * @param status: fills in the outgoing error code
  294. *                could be <TT>U_MISSING_RESOURCE_ERROR</T> if the key is not found
  295. *                could be a non-failing error 
  296. *                e.g.: <TT>U_USING_FALLBACK_ERROR</TT>,<TT>U_USING_DEFAULT_ERROR </TT>
  297. * @see ures_open
  298. * @see ures_openW
  299. */
  300. U_CAPI void U_EXPORT2 ures_close(UResourceBundle*    resourceBundle);
  301. /**
  302.      * Return the version number associated with this ResourceBundle. This version
  303.      * number is a string of the form MAJOR.MINOR, where MAJOR is the version number of
  304.      * the current analytic code package, and MINOR is the version number contained in
  305.      * the resource file as the value of the tag "Version". A change in the MINOR
  306.      * version indicated an updated data file. A change in the MAJOR version indicates a
  307.      * new version of the code which is not binary-compatible with the previous version.
  308.      * If no "Version" tag is present in a resource file, the MINOR version "0" is assigned.
  309.      *
  310.      * For example, if the Collation sort key algorithm changes, the MAJOR version
  311.      * increments. If the collation data in a resource file changes, the MINOR version
  312.      * for that file increments.
  313.      * @param resourceBundle: resource bundle in question
  314.      * @return  A string of the form N.n, where N is the major version number,
  315.      *          representing the code version, and n is the minor version number,
  316.      *          representing the resource data file. The caller does not own this
  317.      *          string.
  318.      */
  319. U_CAPI const char* U_EXPORT2 ures_getVersionNumber(const UResourceBundle*   resourceBundle);
  320. #endif /*_URES*/
  321. /*eof*/
  322.